/*
 * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.util;

/**
 * This class provides a skeletal implementation of the <tt>List</tt> interface
 * to minimize the effort required to implement this interface backed by a
 * "sequential access" data store (such as a linked list). For random access
 * data (such as an array), <tt>AbstractList</tt> should be used in preference
 * to this class.
 * <p>
 *
 * This class is the opposite of the <tt>AbstractList</tt> class in the sense
 * that it implements the "random access" methods (<tt>get(int index)</tt>,
 * <tt>set(int index, E element)</tt>, <tt>add(int index, E element)</tt> and
 * <tt>remove(int index)</tt>) on top of the list's list iterator, instead of
 * the other way around.
 * <p>
 *
 * To implement a list the programmer needs only to extend this class and
 * provide implementations for the <tt>listIterator</tt> and <tt>size</tt>
 * methods. For an unmodifiable list, the programmer need only implement the
 * list iterator's <tt>hasNext</tt>, <tt>next</tt>, <tt>hasPrevious</tt>,
 * <tt>previous</tt> and <tt>index</tt> methods.
 * <p>
 *
 * For a modifiable list the programmer should additionally implement the list
 * iterator's <tt>set</tt> method. For a variable-size list the programmer
 * should additionally implement the list iterator's <tt>remove</tt> and
 * <tt>add</tt> methods.
 * <p>
 *
 * The programmer should generally provide a void (no argument) and collection
 * constructor, as per the recommendation in the <tt>Collection</tt> interface
 * specification.
 * <p>
 *
 * This class is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java
 * Collections Framework</a>.
 *
 * @author Josh Bloch
 * @author Neal Gafter
 * @see Collection
 * @see List
 * @see AbstractList
 * @see AbstractCollection
 * @since 1.2
 */

public abstract class AbstractSequentialList<E> extends AbstractList<E> {
    /**
     * 构造函数
     *
     */
    protected AbstractSequentialList() {
    }

    /**
     * 获取集合中指定位置的元素
     *
     * 实现方式是使用listIterator(int)调用next方法
     *
     * @throws IndexOutOfBoundsException {@inheritDoc}
     */
    public E get(int index) {
        try {
            // 实现方式是使用listIterator(int)调用next方法
            return listIterator(index).next();
        } catch (NoSuchElementException exc) {
            throw new IndexOutOfBoundsException("Index: " + index);
        }
    }

    /**
     * 替换指定位置的元素 其实现方位是为使用列表迭代器 调用列表迭代器的set方法
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     * 
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException {@inheritDoc}
     * 
     * @throws IllegalArgumentException {@inheritDoc}
     * 
     * @throws IndexOutOfBoundsException {@inheritDoc}
     */
    public E set(int index, E element) {
        try {
            // 获取从指定位置的迭代器
            ListIterator<E> e = listIterator(index);
            // 获取原始值
            E oldVal = e.next();
            // 设置新的元素值
            e.set(element);
            return oldVal;
        } catch (NoSuchElementException exc) {
            throw new IndexOutOfBoundsException("Index: " + index);
        }
    }

    /**
     * 在指定位置插入一个新的元素 指定位置及其资之后的元素全部后移一位
     * 
     * @throws UnsupportedOperationException {@inheritDoc}
     * @throws ClassCastException            {@inheritDoc}
     * @throws NullPointerException          {@inheritDoc}
     * @throws IllegalArgumentException      {@inheritDoc}
     * @throws IndexOutOfBoundsException     {@inheritDoc}
     */
    public void add(int index, E element) {
        try {
            // 创建从指定位置开始的列表迭代器 添加元素
            listIterator(index).add(element);
        } catch (NoSuchElementException exc) {
            throw new IndexOutOfBoundsException("Index: " + index);
        }
    }

    /**
     * 删除指定位置的元素
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     * @throws IndexOutOfBoundsException     {@inheritDoc}
     */
    public E remove(int index) {
        try {
            // 获取指定位置开始的列表迭代器
            ListIterator<E> e = listIterator(index);
            // 获取删除元素
            E outCast = e.next();
            // 删除数据
            e.remove();
            return outCast;
        } catch (NoSuchElementException exc) {
            throw new IndexOutOfBoundsException("Index: " + index);
        }
    }

    // 批量操作

    /**
     * 在指定位置插入指定集合全部元素
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     * @throws ClassCastException            {@inheritDoc}
     * @throws NullPointerException          {@inheritDoc}
     * @throws IllegalArgumentException      {@inheritDoc}
     * @throws IndexOutOfBoundsException     {@inheritDoc}
     */
    public boolean addAll(int index, Collection<? extends E> c) {
        try {
            // 修改标记
            boolean modified = false;
            // 获取指定位置开始的列表迭代器
            ListIterator<E> e1 = listIterator(index);
            // 获取指定集合的迭代器
            Iterator<? extends E> e2 = c.iterator();
            // 指定集合进行迭代
            while (e2.hasNext()) {
                // 集合列表迭代器天津爱元素
                e1.add(e2.next());
                // 修改修改标记
                modified = true;
            }
            return modified;
        } catch (NoSuchElementException exc) {
            throw new IndexOutOfBoundsException("Index: " + index);
        }
    }

    // 迭代器

    /**
     * 获取集合迭代器
     *
     * @return an iterator over the elements in this list (in proper sequence)
     */
    public Iterator<E> iterator() {
        // 返回列表迭代器
        return listIterator();
    }

    /**
     * 获取指定位置开始的列表迭代器
     * 抽象方法 如果实现这个类需要实现该方法
     *
     * @param index 指定位置
     * @return a list iterator over the elements in this list (in proper sequence)
     * @throws IndexOutOfBoundsException {@inheritDoc}
     */
    public abstract ListIterator<E> listIterator(int index);
}
